home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_438 / menuc / docs / menuc8.doc < prev    next >
Text File  |  1992-05-06  |  12KB  |  387 lines
  1.  
  2.  
  3.  
  4.                   MenuC
  5.                          The Menu Compiler
  6.               Written by Bruce Mackey
  7.                    (c) 1990,1991
  8.                All Rights Reserved.
  9.  
  10.                Version 0.8
  11.  
  12.           -== INCLUDES DOCUMENTATION FOR GADGET SUPPORT ==-
  13.  
  14.          -== SEARCH FOR '###' to find whats New ==-
  15.          
  16. DISCLAIMER
  17.      Anyone  my  FREELY   distribute   this  program  and  program
  18. documentation, providing that the  program, documentation, and LZH
  19. file remain in there original state. You as the user or distributor
  20. may not charge any money apart from postage or material (eg. Disks).
  21. If you want to bundle this  program  (oh  sure) with some work of
  22. your own you MUST get permission from the author in writing (of course
  23. if it is for a commercial product the author would like some green
  24. backs...er CASH!). addendum: should you use this program in the 
  25. development of a larger program: as author of MenuC I request that;
  26.  
  27. (1) if the program is for the public domain: 
  28.     please acknowledge 'MenuC'
  29. (2) if the author of the program requests/requires that money be paid
  30.     for ownership or for using said progam: 
  31.     please acknowledge 'MenuC' in a VERY BIG way and give a free 
  32.     copy or free use of said program to the author of 'MenuC'. :) :)
  33.  
  34. As the author of MenuC I do not make any claims of copyright for 
  35. files produced by MenuC. No guarantees implied or explicate are given.
  36.  
  37. OVERVIEW
  38.      MenuC was created because I am  sick  and tied of keying in
  39. all the information needed  to create just  one menu, let alone 
  40. FIVE! MenuC will take a VERY  SIMPLE  ascii file and create those 
  41. VERY finger intensive  MENU,  MENUITEM (SUBITEM),  and IntuiText 
  42. structures needed for a complete menu. 
  43.      Support for GADGET,BORDER,PROPINFO,STRINGINFO and USHORT arrays
  44. needed for working gadgets was the next logical step.
  45.  
  46. NOTE: MenuC deals ONLY with TEXT menus/gadgets, no graphics/images.
  47.  
  48. ### Gadgets created will have the WB2.0 raised look.
  49.  
  50.  
  51. SPECIFICS
  52.      MenuC is called from the command line with the following
  53.      format:
  54.  
  55. ###   MenuC infile outfile [LASM|ASM] [TEST] [INFO]
  56.  
  57.      infile and outfile are self exploratory.
  58.  
  59.      LASM - causes the program to produce an assembler output file
  60.         compatible with Lattice's `asm'.
  61.  
  62.       ASM - causes the program to produce an assembler output file
  63.         compatible with MetaComCo's `assem'.
  64.  
  65.      TEST - will cause the program to add a 'C' main() at the end
  66.         of the output file OR an assembler startup routine at
  67.         the start of the output file. The resulting outfile can
  68.         be compiled/assembled as a stand-alone program in order
  69.         to view your menus. Scripts s/MC, s/MCLAsm, s/MCAsm are
  70.         supplied for making MenuC easier to use.
  71.  
  72. ###  INFO - providing no errors occurred MenuC will display a total of
  73.         specific structures that it wrote to the output file.
  74.         INFO DOES NOT report everything MenuC writes to the file.
  75.  
  76.      NOTE:  Output produced by LASM and ASM flags will work with A68k.
  77.  
  78.  
  79.     MenuC is in the second stage of development. Currently it
  80.     recognizes twelve (12) keywords which are as follows:
  81.  
  82.        WIDTH - right now it is used only for the main() routine
  83.            created with the TEST flag from the CLI. Future
  84.            versions will have error checking for screen
  85.                width
  86.  
  87.     MENU - defines the actual menu
  88.  
  89.     ITEM - defines the menu's item
  90.  
  91.      SUBITEM - defines an item's subitem
  92.  
  93.     SHORTCUT - defines a keyboard shortcut for an item or
  94.            subitem
  95.  
  96. ###     BOOL - defines a BOOLGADGET
  97.   
  98. ###   STRING - defines a STRGADGET
  99.       
  100. ###     PROP - defines a PROPGADGET
  101.         
  102. ###  GIMMEZZ - declares the gadget for use with a GIMMEZEROZERO window
  103.     
  104. ###  REQUEST - declares the gadget for use with a REQUESTER
  105.      
  106. ###  LONGINT - defines a STRINGADGET that accepts only numeric data
  107.      
  108. ###  BORDER  - defines border type ( 1.3 or 2.0 )
  109.  
  110.      Keywords can be either upper or lower case and can have white
  111.      space in front of them (for the structured look).
  112.  
  113.  
  114. KEYWORD SYNTAX
  115.  
  116.      WIDTH size   (DEFAULT: 640)
  117.        WIDTH MUST be on the first line of the file and
  118.        can have a value of 320 or 640. This will 
  119.        MAY change when WB2.0 is more widely available.
  120.  
  121.      MENU menu# NAME
  122.        menu# has a range of 1 - n.
  123.        NAME can be a quoted string (see DRAWBACKS below).
  124.  
  125.      ITEM menu# item# NAME [SHORTCUT c]
  126.        menu# and item# have a range of 1 - n.
  127.        menu# MUST be a valid menu number since ITEM will be
  128.        bound to the MENU that owns menu#.
  129.        NAME can be a quoted string (see DRAWBACKS below).
  130.        The 'c' in [SHORTCUT c] can be any printable character
  131.        either upper or lower case.
  132.  
  133.      SUBITEM menu# item# subitem# NAME [SHORTCUT c]
  134.        same description as ITEM with this exception:
  135.           if you have a definition like this:
  136.  
  137.              ITEM 1 1 OPEN SHORTCUT O
  138.              SUBITEM 1 1 1 Documents SHORTCUT D
  139.  
  140.           The ITEM's SHORTCUT will be ignored.
  141.  
  142. ### ------- its not as bad as it looks. take a look at the examples.
  143.  
  144. ###     BOOL [subgadget] NAME llll,tttt wwww,hhhh FLAGS ACTIVATION [GadID]
  145. ###   STRING [subgadget] NAME llll,tttt wwww,hhhh FLAGS ACTIVATION [GadID]
  146. ###     PROP [subgadget] NAME llll,tttt wwww,hhhh FLAGS ACTIVATION [GadID]
  147. ###  LONGINT [subgadget] NAME llll,tttt wwww,hhhh FLAGS ACTIVATION [GadID]
  148.       subgadget can be GIMMEZZ and REQUEST
  149.           using GIMMEZZ with TEST on the command line will cause
  150.           the test program to create a GIMMEZEROZERO window.
  151.       NAME can be a quoted string (see DRAWBACKS below).
  152.       llll is the leftedge of the gadget in base 10
  153.       tttt is the topedge of the gadget in base 10
  154.       wwww is the width of the gadget in base 10
  155.       hhhh is the height of the gadget in base 10
  156.   
  157.      FLAGS and ACTIVATION:
  158.       I tried to make this as easy as possible for the user
  159.       and myself for coding reasons, so I am using the same
  160.       method as the Basic that is shipped with your Amiga.
  161.       The method is that each flag is assigned a value and 
  162.       by adding the values together you get the desired flags
  163.       for the gadget.
  164.    
  165.       Below is the list of flags and there values. 
  166.   
  167.       If all else fails turn to pages 93-94 of the
  168.       revised RKM libs & devs manual, the values
  169.       are in the same order that the flags are listed
  170.       1,2,4,8,16,32,etc.
  171.   
  172.  
  173.  
  174.       flags:
  175.            GADGHCOMP         1
  176.            GADGHBOX        2
  177.            GADGHIMAGE         4    ;not supported yet
  178.            GADGHNONE         8
  179.            GADGIMAGE         16    ;not supported yet
  180.            GRELBOTTOM         32
  181.            GRELRIGHT         64
  182.            GRELWIDTH         128
  183.            GRELHEIGHT         256
  184.            SELECTED         512
  185.            GADGDISABLED        1024
  186.  
  187.       activation:
  188.            TOGGLESELECT     1
  189.            GADGIMMEDIATE    2
  190.            RELVERIFY         4
  191.            ENDGADGERT         8
  192.            FOLLOWMOUSE         16
  193.            RIGHTBORDER         32
  194.            LEFTBORDER         64
  195.            TOPBORDER         128
  196.            BOTTOMBORDER     256
  197.            STRINGCENTER     512
  198.            STRINGRIGHT         1024
  199.            LONGINT          2048     ;USE LONGINT as GADGETTYPE
  200.            ALTKEYMAP         4096    ;not supported yet
  201.            BOOLEXTEND        8192     ;not supported yet
  202.  
  203.  
  204.      example:
  205.           BOOL GIMMEZZ test 10,180 100,9  1025 5 
  206.  
  207.           1025 = GADGHCOMP | GADGDISABLED
  208.              5 = TOGGLESELECT | RELVERIFY
  209.  
  210.           MenuC tries to be as intelligent as possible when it comes
  211.       to the FLAGS and ACTIVATION fields. Meaning that MenuC WILL
  212.       NOT allow flags that in MenuC's opinion conflict with each other.
  213.       Unfortunately, if you don't agree with my choices of exclusion
  214.       you'll have to go back into the outfile and manually change them.
  215.       MenuC just trims the flags so the gadget will work...no more.
  216.       (see DRAWBACKS below)
  217.  
  218.       define a gadget with FLAGS = 2047 & ACTIVATION = 16383
  219.       this will show most of the conflicts.
  220.  
  221.            (see examples/conflicts.men)
  222.  
  223.       you'll see that MenuC WILL create a Gadget, and that
  224.       the gadget's FLAGS & ACTIVATION fields are modified
  225.       to allow the gadget to work correctly.
  226.  
  227.  
  228.       GadID   will allow you to number the gadgets as you see fit.
  229.                 OR
  230.             MenuC will automatically keep track of each gadget's
  231.           GadgetID number. If you have 5 gadgets:
  232.  
  233.               BOOL test1 10,10 20,20 1 3  1025
  234.             BOOL test2 35,10 20,20 1 3         ; ID = 1026
  235.             BOOL test3 55,10 20,20 1 3  3
  236.             BOOL test4 80,10 20,20 1 3         ; ID = 4
  237.             BOOL test5 105,10 20,20 1 3        ; ID = 5
  238.    
  239.           gadget test1 will have an ID of 1025 and each
  240.           gadget after test1 will incremented by 1.
  241.  
  242.           The last 3 will have GadIDs 3,4,5.
  243.               (the outfile will have DEFINEs/EQUs for each GadID)
  244.   
  245.           If no values are specified for GadID the numbering
  246.           starts at ONE (1). If you want it to start at 
  247.           ZERO (0) then assign a ZERO (0) as GadID on the 
  248.           very first gadget in the source file.
  249.  
  250. ###   BORDER  version  (DEFAULT: 1.3)
  251.        version is defined as either '1.3' OR '2.0'.
  252.       I have little to no knowledge of programing in the 2.0 
  253.       environment. So all that 'BORDER 2.0' will do is simply
  254.       switch the FRONTPEN and BACKPEN fields of the Border and
  255.       IntuiText structures.
  256.  
  257.  
  258.   
  259. DRAWBACKS
  260.  
  261.      1. In version 0.8 text length is not adjusted to the longest
  262.     length of an ITEM or SUBITEM to get around this you will
  263.     have to quote NAMEs to the largest length.
  264.  
  265.         eg.   ITEM 1 1 "TEST     "
  266.               ITEM 1 2 Documents
  267.  
  268.      2. When NAMEs are quoted in version 0.8 the program (when
  269.     creating the actual structures) will insert an underscore
  270.     into all white spaces.
  271.     So if you have an ITEM's NAME define as FILE the
  272.     program will create structs like  FILE_menu. If on the
  273.     other hand the ITEM's NAME is defined as "FILE   " then
  274.     the structs will be created as FILE____menu, note four
  275.     underscores, one for each white space and one for _menu.
  276.  
  277.     (gadget support handles names the same as described in no 2.)
  278.  
  279.  
  280.      3. As of this writing I don't really consider this
  281.     description as a DRAWBACK but...
  282.     The program ALWAYS adds space to the right side of an
  283.     ITEM/SUBITEM for Intuition's Command key sequence,
  284.     Right AMIGA-A commandkey.
  285.  
  286.      4. In version 0.8 menus created are for HIRES screens (640-200).
  287.     The WIDTH keyword does not affect the screen width (as of yet).
  288.  
  289. ###  5. there is no support for using images.     
  290.      
  291. ###  6. When pruning the FLAGS & ACTIVATION fields MenuC fakes intelligence,
  292.     it is possible to have a gadget on the left side of the screen
  293.     with the flag RIGHTBORDER set. This might be just want you want
  294.     but I doubt that it would be a common request. MenuC only cares 
  295.     if the gadget will work (examine the gadget created from
  296.     examples/conflicts.men).
  297.  
  298.  
  299. Would you like to have something added ?
  300. Do you have ideas on improving MenuC ?
  301. Do you have a bug report ?
  302.  
  303. Please, Contact me.
  304.  
  305. CIS:  72567,2601
  306. BIX:  bmackey
  307.  
  308. or at BBS's that I frequent:
  309.  
  310. Lion's Den:     516-399-1928
  311. AmiAdvocat: 615-776-5438
  312. CA-AUG:  216-642-3344
  313. Lattice's BBS:  708-916-1200
  314.  
  315. mailing address:
  316.  
  317. Bruce Mackey
  318. 4040 Avoca Ave
  319. Bethpage NY 11714
  320. 516-935-2075 or
  321. 516-935-5292
  322.  
  323.  
  324. REVISION HISTORY
  325.  
  326.     Version        Revision
  327.     -------        --------
  328.  
  329.     0.5          initial release (6-14-90)
  330.     0.6        internal added assembler support.
  331.             added `ASM' and `LASM' command line switches.
  332.  
  333.     0.7        fixed bug with improper WIDTH size.
  334.             fixed bug with erroneous SHORTCUT commands.
  335.  
  336. ###    0.7.7 internal        
  337.             o fixed all of the enforcer hits.
  338.             o shaved approx. 1100 bytes from the code.
  339.             o repaired some embarrassing bugs in the file 
  340.               output routines.
  341.             o optimized the speed slightly.
  342.  
  343.             o ADDED GADGET SUPPORT (whew!)
  344.               and the program got a little fatter and slower.
  345. ###    0.8 
  346.             o added subgadgets GIMMEZZ and REQUEST
  347.             o removed redundancy in the Border output area.
  348.               MenuC will output ONLY ONE INSTANCE of like 
  349.               Borders.
  350.             o added check for conflicting GADGET FLAGS
  351.               and GADGET ACTIVATION fields.
  352.              o added INFO function. (see command line)
  353.  
  354. END REVISION HISTORY
  355.  
  356. TO DO
  357.      o add an Intuition 'Point and Click' interface 
  358.        constructive suggestions?
  359.        let me know.  (see addresses above)
  360.  
  361.  
  362. ###     o  would anyone like to contribute support for images.
  363.        I would prefer a stand-alone program that I could  
  364.        bundle with MenuC. If you already have one written 
  365.        then it would require a VERY SMALL modification for 
  366.         use with MenuC8.
  367.   
  368.   
  369.            (queue announcer)
  370.    
  371.       YES, NOW YOU TOO CAN HAVE PART OF THE HEADLINES,
  372.       FAME, AND FORTUNE WITH JUST A SMALL EFFORT AND
  373.  
  374.            (through an echo chamber)
  375.  
  376.              !!!!!! NO MONEY DOWN !!!!!!
  377.  
  378.            (applause)
  379.  
  380.            (run credits) <-------- YOUR NAME HERE
  381.  
  382.  
  383. SAS/C is a trademark of SAS Institute inc.
  384. Lattice is a trademark of Lattice Incorporated.
  385. MetaComco is a trademark of MetaComco plc.
  386. A68k (c) Brian R. Anderson, AmigaDOS version by Charlie Gibbs.
  387.